package ks.framework.interfaces;

import ks.framework.common.Message;
import ks.framework.communicator.Communicator;

/**
 * Authorization interface to enable proper authorization of both ordinary users
 * as well as administrators. 
 * 
 * @author George Heineman
 */
public interface IAuthorization {

	/** 
	 * Authorize the given user with SHA-1 hashed password.
	 * <p>
	 * If the authorization would otherwise succeed, but for other
	 * reasons it must be denied, then throw an Exception.
	 * 
	 * @param who
	 * @param pwd
	 * @return <code>true</code> if the credentials match; <code>false</code>
	 * otherwise
	 * @throws Exception if the system is prevented from otherwise authorizing
	 * the user. Information about why is included in the Exception.
	 */
	boolean authorize(String who, String pwd) throws Exception;

	/** 
	 * Self-register user with the given password hash and assign an id.
	 * <p>
	 * 
	 * @param password    the hashed value of the client's selected password.
	 * @return            returns the playerID that was created by request.
	 */
	String selfRegister(String password);

	/** 
	 * Upon successful login and authorization, this method is called.
	 * <p>
	 * It contains the original message and the communicator, should that
	 * be necessary.
	 * 
	 * @param com
	 * @param m
	 */
	void login (Communicator com, Message m);

	/** 
	 * Upon successful logout, this method is called.
	 * <p>
	 * It contains the original message and the communicator, should that
	 * be necessary.
	 * 
	 * @param com
	 * @param m
	 */
	void logout (Communicator com, Message m);

}
